home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3 / SCSL / dhsein.z / dhsein
Encoding:
Text File  |  2002-10-03  |  9.5 KB  |  265 lines
  1.  
  2.  
  3.  
  4. DDDDHHHHSSSSEEEEIIIINNNN((((3333SSSS))))                                                          DDDDHHHHSSSSEEEEIIIINNNN((((3333SSSS))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      DHSEIN - use inverse iteration to find specified right and/or left
  10.      eigenvectors of a real upper Hessenberg matrix H
  11.  
  12. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  13.      SUBROUTINE DHSEIN( SIDE, EIGSRC, INITV, SELECT, N, H, LDH, WR, WI, VL,
  14.                         LDVL, VR, LDVR, MM, M, WORK, IFAILL, IFAILR, INFO )
  15.  
  16.          CHARACTER      EIGSRC, INITV, SIDE
  17.  
  18.          INTEGER        INFO, LDH, LDVL, LDVR, M, MM, N
  19.  
  20.          LOGICAL        SELECT( * )
  21.  
  22.          INTEGER        IFAILL( * ), IFAILR( * )
  23.  
  24.          DOUBLE         PRECISION H( LDH, * ), VL( LDVL, * ), VR( LDVR, * ),
  25.                         WI( * ), WORK( * ), WR( * )
  26.  
  27. IIIIMMMMPPPPLLLLEEEEMMMMEEEENNNNTTTTAAAATTTTIIIIOOOONNNN
  28.      These routines are part of the SCSL Scientific Library and can be loaded
  29.      using either the -lscs or the -lscs_mp option.  The -lscs_mp option
  30.      directs the linker to use the multi-processor version of the library.
  31.  
  32.      When linking to SCSL with -lscs or -lscs_mp, the default integer size is
  33.      4 bytes (32 bits). Another version of SCSL is available in which integers
  34.      are 8 bytes (64 bits).  This version allows the user access to larger
  35.      memory sizes and helps when porting legacy Cray codes.  It can be loaded
  36.      by using the -lscs_i8 option or the -lscs_i8_mp option. A program may use
  37.      only one of the two versions; 4-byte integer and 8-byte integer library
  38.      calls cannot be mixed.
  39.  
  40. PPPPUUUURRRRPPPPOOOOSSSSEEEE
  41.      DHSEIN uses inverse iteration to find specified right and/or left
  42.      eigenvectors of a real upper Hessenberg matrix H. The right eigenvector x
  43.      and the left eigenvector y of the matrix H corresponding to an eigenvalue
  44.      w are defined by:
  45.  
  46.                   H * x = w * x,     y**h * H = w * y**h
  47.  
  48.      where y**h denotes the conjugate transpose of the vector y.
  49.  
  50.  
  51. AAAARRRRGGGGUUUUMMMMEEEENNNNTTTTSSSS
  52.      SIDE    (input) CHARACTER*1
  53.              = 'R': compute right eigenvectors only;
  54.              = 'L': compute left eigenvectors only;
  55.              = 'B': compute both right and left eigenvectors.
  56.  
  57.      EIGSRC  (input) CHARACTER*1
  58.              Specifies the source of eigenvalues supplied in (WR,WI):
  59.              = 'Q': the eigenvalues were found using DHSEQR; thus, if H has
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. DDDDHHHHSSSSEEEEIIIINNNN((((3333SSSS))))                                                          DDDDHHHHSSSSEEEEIIIINNNN((((3333SSSS))))
  71.  
  72.  
  73.  
  74.              zero subdiagonal elements, and so is block-triangular, then the
  75.              j-th eigenvalue can be assumed to be an eigenvalue of the block
  76.              containing the j-th row/column.  This property allows DHSEIN to
  77.              perform inverse iteration on just one diagonal block.  = 'N': no
  78.              assumptions are made on the correspondence between eigenvalues
  79.              and diagonal blocks.  In this case, DHSEIN must always perform
  80.              inverse iteration using the whole matrix H.
  81.  
  82.      INITV   (input) CHARACTER*1
  83.              = 'N': no initial vectors are supplied;
  84.              = 'U': user-supplied initial vectors are stored in the arrays VL
  85.              and/or VR.
  86.  
  87.      SELECT  (input/output) LOGICAL array, dimension (N)
  88.              Specifies the eigenvectors to be computed. To select the real
  89.              eigenvector corresponding to a real eigenvalue WR(j), SELECT(j)
  90.              must be set to .TRUE.. To select the complex eigenvector
  91.              corresponding to a complex eigenvalue (WR(j),WI(j)), with complex
  92.              conjugate (WR(j+1),WI(j+1)), either SELECT(j) or SELECT(j+1) or
  93.              both must be set to
  94.  
  95.      N       (input) INTEGER
  96.              The order of the matrix H.  N >= 0.
  97.  
  98.      H       (input) DOUBLE PRECISION array, dimension (LDH,N)
  99.              The upper Hessenberg matrix H.
  100.  
  101.      LDH     (input) INTEGER
  102.              The leading dimension of the array H.  LDH >= max(1,N).
  103.  
  104.      WR      (input/output) DOUBLE PRECISION array, dimension (N)
  105.              WI      (input) DOUBLE PRECISION array, dimension (N) On entry,
  106.              the real and imaginary parts of the eigenvalues of H; a complex
  107.              conjugate pair of eigenvalues must be stored in consecutive
  108.              elements of WR and WI.  On exit, WR may have been altered since
  109.              close eigenvalues are perturbed slightly in searching for
  110.              independent eigenvectors.
  111.  
  112.      VL      (input/output) DOUBLE PRECISION array, dimension (LDVL,MM)
  113.              On entry, if INITV = 'U' and SIDE = 'L' or 'B', VL must contain
  114.              starting vectors for the inverse iteration for the left
  115.              eigenvectors; the starting vector for each eigenvector must be in
  116.              the same column(s) in which the eigenvector will be stored.  On
  117.              exit, if SIDE = 'L' or 'B', the left eigenvectors specified by
  118.              SELECT will be stored consecutively in the columns of VL, in the
  119.              same order as their eigenvalues. A complex eigenvector
  120.              corresponding to a complex eigenvalue is stored in two
  121.              consecutive columns, the first holding the real part and the
  122.              second the imaginary part.  If SIDE = 'R', VL is not referenced.
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. DDDDHHHHSSSSEEEEIIIINNNN((((3333SSSS))))                                                          DDDDHHHHSSSSEEEEIIIINNNN((((3333SSSS))))
  137.  
  138.  
  139.  
  140.      LDVL    (input) INTEGER
  141.              The leading dimension of the array VL.  LDVL >= max(1,N) if SIDE
  142.              = 'L' or 'B'; LDVL >= 1 otherwise.
  143.  
  144.      VR      (input/output) DOUBLE PRECISION array, dimension (LDVR,MM)
  145.              On entry, if INITV = 'U' and SIDE = 'R' or 'B', VR must contain
  146.              starting vectors for the inverse iteration for the right
  147.              eigenvectors; the starting vector for each eigenvector must be in
  148.              the same column(s) in which the eigenvector will be stored.  On
  149.              exit, if SIDE = 'R' or 'B', the right eigenvectors specified by
  150.              SELECT will be stored consecutively in the columns of VR, in the
  151.              same order as their eigenvalues. A complex eigenvector
  152.              corresponding to a complex eigenvalue is stored in two
  153.              consecutive columns, the first holding the real part and the
  154.              second the imaginary part.  If SIDE = 'L', VR is not referenced.
  155.  
  156.      LDVR    (input) INTEGER
  157.              The leading dimension of the array VR.  LDVR >= max(1,N) if SIDE
  158.              = 'R' or 'B'; LDVR >= 1 otherwise.
  159.  
  160.      MM      (input) INTEGER
  161.              The number of columns in the arrays VL and/or VR. MM >= M.
  162.  
  163.      M       (output) INTEGER
  164.              The number of columns in the arrays VL and/or VR required to
  165.              store the eigenvectors; each selected real eigenvector occupies
  166.              one column and each selected complex eigenvector occupies two
  167.              columns.
  168.  
  169.      WORK    (workspace) DOUBLE PRECISION array, dimension ((N+2)*N)
  170.  
  171.      IFAILL  (output) INTEGER array, dimension (MM)
  172.              If SIDE = 'L' or 'B', IFAILL(i) = j > 0 if the left eigenvector
  173.              in the i-th column of VL (corresponding to the eigenvalue w(j))
  174.              failed to converge; IFAILL(i) = 0 if the eigenvector converged
  175.              satisfactorily. If the i-th and (i+1)th columns of VL hold a
  176.              complex eigenvector, then IFAILL(i) and IFAILL(i+1) are set to
  177.              the same value.  If SIDE = 'R', IFAILL is not referenced.
  178.  
  179.      IFAILR  (output) INTEGER array, dimension (MM)
  180.              If SIDE = 'R' or 'B', IFAILR(i) = j > 0 if the right eigenvector
  181.              in the i-th column of VR (corresponding to the eigenvalue w(j))
  182.              failed to converge; IFAILR(i) = 0 if the eigenvector converged
  183.              satisfactorily. If the i-th and (i+1)th columns of VR hold a
  184.              complex eigenvector, then IFAILR(i) and IFAILR(i+1) are set to
  185.              the same value.  If SIDE = 'L', IFAILR is not referenced.
  186.  
  187.      INFO    (output) INTEGER
  188.              = 0:  successful exit
  189.              < 0:  if INFO = -i, the i-th argument had an illegal value
  190.              > 0:  if INFO = i, i is the number of eigenvectors which failed
  191.              to converge; see IFAILL and IFAILR for further details.
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. DDDDHHHHSSSSEEEEIIIINNNN((((3333SSSS))))                                                          DDDDHHHHSSSSEEEEIIIINNNN((((3333SSSS))))
  203.  
  204.  
  205.  
  206. FFFFUUUURRRRTTTTHHHHEEEERRRR DDDDEEEETTTTAAAAIIIILLLLSSSS
  207.      Each eigenvector is normalized so that the element of largest magnitude
  208.      has magnitude 1; here the magnitude of a complex number (x,y) is taken to
  209.      be |x|+|y|.
  210.  
  211.  
  212. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  213.      INTRO_LAPACK(3S), INTRO_SCSL(3S)
  214.  
  215.      This man page is available only online.
  216.  
  217.  
  218.  
  219.  
  220.  
  221.  
  222.  
  223.  
  224.  
  225.  
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.